Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Using the TABLE form

When you pass a static temp-table between two routines, you can use the INPUT TABLE, INPUT-OUTPUT TABLE, and OUTPUT TABLE forms you learned about earlier. To review them, in the RUN statement in the calling program, you define a temp-table parameter in this way:

[ INPUT ] TABLE temp-table-name | { INPUT-OUTPUT | OUTPUT } TABLE temp-table-name [ APPEND ] [ BY-REFERENCE ] [ BIND ]

In the routine that is called, you define the table as a parameter in this way for an INPUT or INPUT-OUTPUT parameter:

DEFINE [ INPUT | INPUT-OUTPUT ]    PARAMETER TABLE FOR temp-table-name [ APPEND ] [ BIND ].

For an OUTPUT temp-table parameter returned from a called routine, you use this syntax:

DEFINE OUTPUT PARAMETER TABLE FOR temp-table-name [ BIND ].

Remember that you must include a compatible static definition of the temp-table on both sides of the call. This means that at least the number and data types of fields must match in the two table definitions.

What happens when you pass a temp-table in this way? Progress packages up a description of the table and its fields and indexes, along with all the data in all the rows of the temp-table, and marshals it in a single stream from one routine to the other. This means that the temp-table is copied into the routine on the OUTPUT side of the call. To understand the implications of this, consider the two basic ways in which one routine can call another.

Passing the TABLE within a session

Within a single run-time session, if one routine calls another and passes a temp-table as a parameter, you wind up with two complete copies of the temp-table and all its data within that session. This is unnecessary in many cases and can be expensive. It takes a lot of memory to copy a large table, and (relatively speaking) a lot of time to copy it. In many cases, your application doesn’t need two copies of the table. To avoid copying the table and thereby gain a significant performance advantage, you can pass temp-table parameters by reference or by binding (starting with OpenEdge Release 10.1A). These optional means of passing static temp-tables as parameters are described in Chapter 11, " Defining and Using Temp-tables."

Alternately, you can simply pass a temp-table’s HANDLE. Remember that for any kind of object, if you make the handle of the object available to another routine within the session, the other routine can access that object, its data, and its attributes regardless of where the object was defined or created. This holds true for a temp-table as well. Using the temp-table handle your routine can get at its buffer, along with all the data in the table.

When should you consider passing the TABLE within a session? If both routines use static temp-table definitions and static Progress 4GL language statements to access the table, then you need to pass the table itself instead of its handle. If you pass the handle, then the routine that receives the temp-table can only manipulate it through its handle, using dynamic buffer and buffer field methods and attributes. If the two routines have compatible but different definitions of the same table with, for example, different field names for the fields in the same relative positions within the temp-table buffer, you can successfully pass this table from one routine to the other. In the course of copying it, Progress moves the data into the fields as they are defined in the routine that receives the table.

If you need to pass the table itself because your routines need to manage it with static 4GL statements, then do what you can to minimize the amount of data you pass. If the routine is only going to look at a subset of the records in the temp-table (for example, those that have been changed since they were created or since the receiving routine last saw them), then it might be more efficient to create a second smaller temp-table containing only those records that really need to be passed. If you simply keep in mind that there is an overhead to passing the table, this should influence your design and programming to minimize the overhead.

Passing the TABLE between sessions

If you need to pass a temp-table from one session to a completely separate session, and at least you have a static temp-table definition on the sending side, then you should use the TABLE form. Object handles aren’t meaningful between sessions because they define memory locations within a single session. And when you pass a handle you are passing only a pointer to that memory location, not the contents. For this reason, if you need to pass a static temp-table from an AppServer session (that, for example, reads data out of the database and loads it into the table) to a client session that needs to use the data without a database connection, then use the TABLE form. You have no choice but to copy all the data from one session to the other. Again, the two temp-table definitions do not need to be identical. They need to have the same signature, the same number of fields, and the same data types in the same order.